前兩天我們看了兩個很完整的系統。

Day 25 的 Claude Code 告訴我們：

一個 Model 要安全地修改真實 Repository，需要完整的 Tool、Permission、Context、Hook 與 Verification Harness。

Day 26 的 Hermes 告訴我們：

一個 Agent 要跨 Session 長期存在，需要 Memory、Skills、Scheduling、Channels 與 Event Routing。

今天故意走到另一個極端。

如果我們把很多東西拿掉：

• 沒有複雜 Tool Registry
• 沒有很多專用 File Tools
• 沒有長期 Memory
• 沒有 Multi-Agent Coordination
• 沒有大型 Workflow Engine
• 沒有複雜 Plugin System

只留下：

Model
+
Loop
+
Bash
+
Environment
+
Budget
+
Submission / Evaluation

這樣還算 Agent 嗎？

答案是：

可以。

這就是 mini-swe-agent 最值得看的地方。

Awesome Agent Architecture 研究的版本固定在 v2.4.5，把它當成一個約 150 行、單一 Bash Tool 的研究基線，用來觀察：

哪些 Harness Layer 是真正必要的，哪些只是為了解決更複雜的產品 Failure Mode 才加入？

第一個錯誤等號：Harness 越完整，Agent 才越強

前 26 天，我們一直在加東西。

很容易形成一個錯覺：

更多 Tool
+
更多 Planner
+
更多 Subagent
+
更多 Memory
+
更多 Graph
=
更強 Agent

但 mini-swe-agent 提醒我們：

如果 Model 本身已經有很強的 Software Engineering 能力，Harness 有時候可以非常小。

真正值得問的不是：

還能加什麼功能？

而是：

少掉這個 Mechanism，哪一個可觀察 Failure 會增加？

如果答不出來，可能根本不需要加。

1. 最小 Loop

mini-swe-agent 的核心可以概念化成：

Task
↓
Model
↓
Action
↓
Bash
↓
Observation
↓
Model
↓
...
↓
Submit

它仍然有 Agent 最基本的閉環：

Reason
↓
Act
↓
Observe
↓
Reason

這再次證明：

Agent 的最小核心不是 Framework。

而是：

Model 能把 Observation 轉成下一個 Action，而且 Harness 能真的執行 Action。

2. 一個 Bash Tool 為什麼可以做這麼多事？

很多 Agent Framework 會建立：

read_file
write_file
search_files
run_tests
git_diff
install_package

mini-swe-agent 的思路更激進：

Shell 本身已經是一個通用 Computer Interface。

模型可以用：

sed
grep
find
python
pytest
git
cat

完成大量工作。

這有一個很大的優點：

Harness 不需要替每一個 Action 都設計新的 Tool。

新增 Capability 的成本很低。

Model 只需要學會如何使用現成 Unix Environment。

3. Tool Abstraction 越薄，Model Responsibility 越大

這個設計不是沒有代價。

如果只有 Bash：

Harness 不會幫你明確區分：

Read File
vs
Delete File
vs
Run Test
vs
Modify Repo

大量語意都落到 Model。

也就是：

Rich Harness
把更多責任放在 Code

Minimal Harness
把更多責任放在 Model

這是一個非常重要的 Trade-off。

mini-swe-agent 不是證明：

Tool Runtime 不重要。

而是證明：

Tool Runtime 可以薄到只剩一個通用入口，只要 Domain 和 Risk 允許。

4. Bash-only 也讓 Tool Schema 幾乎消失

如果每個 Tool 都需要 Schema：

read_file(path)
write_file(path, content)
search(query, scope)

模型每一輪都要看到大量 Tool Description。

Bash-only 的 Tool Surface 很小。

這會降低：

• Tool Schema Token
• Tool Selection Complexity
• Registry Maintenance

代價則是：

• Action Granularity 更粗
• Permission 更難精細
• Shell Safety 更難控制
• Model 必須自己知道正確 Command

所以這不是免費的簡化。

是把 Complexity 從 Harness 移到 Model 和 Environment。

5. 每一個 Action 都是獨立 Shell Execution

mini-swe-agent 一個很值得看的設計是：

不需要維持一個複雜的 Stateful Shell Session。

每次 Action 可以獨立透過 subprocess 執行。

這降低很多 Harness Complexity：

• 不需要維護 Interactive Shell Protocol
• 不需要追蹤 Shell Prompt
• 不需要 Shell Process 長期存活
• Crash 後比較容易恢復

但它也代表：

需要長期 Shell State 的行為要透過 Filesystem 或 Command 自己保存。

這就是 Minimalism 的典型取捨。

6. Environment 才是 Bash Agent 真正的 Toolset

只有一個 Bash Tool，看起來 Agent 能力很少。

其實真正 Capability 來自 Environment 裡有哪些程式。

例如：

git
python
pytest
node
compiler
package manager

所以完整架構其實是：

Model
↓
Bash
↓
Environment

不是：

Model
↓
One Tiny Tool

Bash 只是通往 Environment 的 Gateway。

這提醒我們：

Tool Count 不是 Capability Count。

一個通用 Tool 可能比二十個專用 Tool 更有能力。

7. Context Management：不做 Compaction，也是一種 Architecture Decision

長 Session 最常見策略是：

Context 快滿
↓
Summary
↓
繼續

mini-swe-agent 走得更簡單。

它假設：

Run 應該在 Budget 內結束，不需要把一個 Session 無限延長。

所以它可以不用完整 Compaction System。

對 Tool Observation 則採取簡單截斷策略，例如只保留有限大小的輸出，避免一個 Command 直接塞爆 Context。

這個設計非常值得注意：

不是每個 Agent 都需要解決「永遠活下去」的問題。

如果你的 Task 本來就應該：

在有限 Budget 內完成或失敗

那 Hard Budget 可能比複雜 Context Compaction 更合理。

8. Budget 是 mini-swe-agent 最重要的 Harness

當 Harness 很薄時，最重要的控制反而更清楚：

你可以自由探索
但不能無限探索

所以 Step Budget、Cost Budget 變成核心。

概念上：

for step in range(max_steps):
    action = model(...)
    observation = env.execute(action)

fail("budget exhausted")

這就是 Day 23 的原則：

Budget before start.

Model 可以自由決定每一步。

但 Harness 決定它有多少步。

9. Budget 其實取代了一部分 Context Engineering

比較完整的 Agent 會說：

Context 快滿了，我要 Compact。

mini-swe-agent 的回答比較接近：

如果你跑到 Context 快滿，可能這次 Run 本來就應該結束。

這不是永遠正確。

但對 SWE-bench 這類 bounded task 很合理。

也就是：

Long-lived Assistant
需要 Context Survival

Bounded Benchmark Agent
可能只需要 Run Budget

Architecture 必須和 Task Horizon 配對。

10. Submit：Completion 需要 Protocol

如果 Agent 只要輸出一句：

Done.

Runner 怎麼知道它真的要結束？

mini-swe-agent 類系統會有一個明確 Submission / Completion Protocol。

也就是模型不是只用自然語言表示：

我覺得完成。

而是執行一個被 Harness 認得的完成 Action。

概念上：

Agent Work
↓
submit
↓
Runner stops
↓
External Evaluation

這和 Day 18 Protocols 的概念一樣。

11. Completion 和 Correctness 仍然分開

submit 只代表：

Agent 決定不再工作。

它不代表：

Patch 是正確的。

真正 Correctness 由外部 Evaluation 決定。

例如：

Agent
↓
Patch
↓
Submit
↓
SWE-bench / tests
↓
Pass or Fail

這是一個非常乾淨的 Responsibility Split：

Model
決定：
我要交卷

Harness
決定：
停止 Run

Evaluator
決定：
你答對了嗎

這和 Day 22 的 Evaluation 直接接起來。

12. Offline Eval 讓 Minimal Agent 特別適合研究

完整 Product Agent 很難比較。

因為一次修改可能同時改變：

• Prompt
• Tool
• UI
• Permission
• Memory
• User Behavior

mini-swe-agent 的優勢是變數少。

所以更適合問：

同一 Harness
換 Model
差多少？

同一 Model
改 Prompt
差多少？

增加一個 Mechanism
值不值得？

這就是 Research Baseline 的價值。

13. Minimal Harness 讓 Attribution 更容易

假設一個 30 萬行 Harness 成功率上升 5%。

很難知道是哪一層造成。

如果 Agent Core 只有約 150 行：

行為更容易追。

這也是為什麼極簡系統很適合：

• Teaching
• Ablation
• Benchmark
• Model Comparison
• Harness Research

它不是一定比較適合所有 Production Product。

但它非常適合回答：

真正最低限度需要什麼？

14. mini-swe-agent 的 Context Failure 很直接

它沒有大量 Context Rescue Mechanism。

所以一個長 Tool Output、長 History 很容易直接撞限制。

這聽起來是缺點。

但它同時有一個研究上的優點：

Failure 很透明。

你不需要先 Debug：

• Summary 是否壓錯
• Memory 是否 Recall 錯
• Skill 是否污染 Context
• Subagent Handoff 是否丟資訊

因為這些 Layer 根本不存在。

Minimal Harness 的優點之一就是：

Failure Attribution 清楚。

15. Confirm Gate：即使極簡，也不能完全沒有 Control

A3 對 mini-swe-agent Harness Thesis 的整理仍然保留一個很重要的控制概念：

one loop
one bash tool
confirm gate
step and cost budgets

這件事很有意思。

即使一個 Agent 極端追求簡單，還是不能完全沒有：

• Stop Boundary
• Cost Boundary
• Execution Boundary

這些是 Harness 最接近「不可刪」的部分。

16. mini-swe-agent 和 Claude Code 的對照

兩個系統不是誰比較正確。

它們在解不同問題。

17. mini-swe-agent 和 Hermes 的對照

Hermes 需要：

Memory
Skills
Channels
Cron
Persistent Session

因為它要跨時間存在。

mini-swe-agent 的一個 Run 是：

Task
↓
Work
↓
Submit
↓
Grade
↓
End

它不需要記住你下週回來會做什麼。

所以沒有理由加入大量 Long-term State。

這就是：

Task Horizon 決定 Harness Depth。

18. 「模型變強後，Harness 能不能變小？」是 mini 最重要的問題

如果 Model 很弱，Harness 可能需要：

• 強制 Planning
• 專用 Search Tool
• 大量 Workflow
• Retry Heuristic
• Format Repair
• 固定 Tool Order

Model 變強後，有些 Layer 可能反而限制它。

所以 Harness 不應該永遠只加不減。

每次 Model Upgrade，都應該重新問：

這個 Layer 現在還有 measurable value 嗎？

如果沒有：

刪掉。

這也是 A3 Harness Thesis 很重要的一部分。

Failure Modes

1. 把 Minimalism 當宗教：真實 Product 需要的 Permission、Memory、Async 不能因為追求短程式碼就忽略。
2. Bash Tool Surface 太大：很難做精細的 Action-level Permission。
3. Observation 太長：沒有完整 Compaction，容易碰 Context Limit。
4. Budget 太小：Agent 有能力完成，但 Harness 太早停止。
5. Budget 太大：Minimal Loop 也可以燒出很大的 Token Bill。
6. Submit 被當成 Success：自我宣告完成不等於 Patch 正確。
7. Benchmark 成功直接推論 Product Ready：Benchmark Environment 和真實安全、協作、身份、權限問題不同。

從 mini-swe-agent 學到的七個原則

1. 先證明最小 Agent 不夠，再加 Harness Layer。
2. Tool Count 不等於 Capability Count。
3. 通用 Environment 可以讓 Tool Abstraction 極薄。
4. Task 有明確 Horizon 時，Budget 可以取代部分長期 Context Mechanism。
5. Completion Protocol 和 Correctness Evaluation 要分開。
6. Harness 越小，Failure Attribution 越容易。
7. Model 變強後，舊 Harness Layer 應該重新做 Ablation。

今天的結論

mini-swe-agent 最值得學的不是：

怎麼用 150 行做出 Claude Code？

它真正提出的是一個更重要的工程問題：

這個 Harness Mechanism 到底是在解真實 Failure，還是只是因為 Framework 可以加，所以我們就加了？

Claude Code 告訴我們完整 Harness 長什麼樣。

Hermes 告訴我們 Long-term Agent 需要什麼。

mini-swe-agent 則提醒我們：

Harness 的最終目標不是變大，而是保留最少、但足以讓 Agent 可靠工作的控制。

下一篇，我們會看第四種完全不同的答案。

如果不是把 Agent 做成一個固定 Class，也不是把所有功能寫進同一個 Runtime，而是：

連 Agent Loop 本身都只是一個可以 Mount / Unmount 的 Plugin。

那架構會變成什麼？

Day 28：DeepSeek Harness。

完整系列與程式碼範例收錄於 https://github.com/hardness1020/awesome-agent-architecture